---
title: "Dictionary"
description: "Dictionary data structure in ReScript"
canonical: "/docs/manual/dict"
section: "Language Features"
order: 8
---

# Dictionary

ReScript has first class support for dictionaries. Dictionaries are mutable objects with string keys, where all values must have the same type. Dicts compile to regular JavaScript objects at runtime.

## Create

You can create a new dictionary in a few different ways, depending on your use case.

<CodeTab labels={["ReScript", "JS Output"]}>

```res prelude
// Using the first class dict syntax
let d = dict{"A": 5, "B": 6}

// Programatically via the standard library
let d2 = Dict.fromArray([("A", 5), ("B", 6)])
```

```js
let d = {
  A: 5,
  B: 6,
};

let d2 = Object.fromEntries([
  ["A", 5],
  ["B", 6],
]);
```

</CodeTab>

A few things to note here:

- Using the first class `dict{}` syntax compiles cleanly to a JavaScript object directly
- Using `Dict.fromArray` is useful when you need to create a dictionary programatically

## Access

You can access values from a Dictionary either via the the standard library `Dict` module functions, or using pattern matching.

<CodeTab labels={["ReScript", "JS Output"]}>

```res prelude
let d = dict{"A": 5, "B": 6, "C": 7}

// Using `Dict.get`
let a = d->Dict.get("A")

// Switching on the full dict
let b = switch d {
| dict{"B": b} => Some(b)
| _ => None
}

// Destructuring
let dict{"C": ?c} = d
```

```js
let d = {
  A: 5,
  B: 6,
  C: 7,
};

let a = d["A"];

let b = d.B;

let b$1 = b !== undefined ? b : undefined;

let c = d.C;
```

</CodeTab>

> In the Destructuring example, we're using the `?` optional pattern match syntax to pull out the `C` key value as an optional, regardless of if the dict has it or not.

## Pattern matching

Dictionaries have first class support for pattern matching. Read more in the [dedicated guide on pattern matching and destructring in ReScript](./pattern-matching-destructuring.mdx#match-on-dictionaries).

## Updating and setting values

You can set and update new values on your dictionary using the `Dict.set` function. All updates are mutable.

<CodeTab labels={["ReScript", "JS Output"]}>

```res prelude
let d = dict{"A": 5, "B": 6}

d->Dict.set("C", 7)
```

```js
let d = {
  A: 5,
  B: 6,
};

d["C"] = 7;
```

</CodeTab>

## Advanced example: Pattern matching on JSON

JSON objects are represented as dictionaries (`dict<JSON.t>`). You can leverage that fact to decode JSON in a nice way, using only language features:

<CodeTab labels={["ReScript", "JS Output"]}>

```res prelude
type user = {
  name: string,
  email: string,
}

/** Decode JSON to a `user`. */
let decodeUser = (json: JSON.t) => {
  switch json {
  | Object(dict{"name": JSON.String(name), "email": JSON.String(email)}) =>
    Some({name, email})
  | _ => None
  }
}

```

```js
function decodeUser(json) {
  if (typeof json !== "object" || json === null || Array.isArray(json)) {
    return;
  }
  let name = json.name;
  if (typeof name !== "string") {
    return;
  }
  let email = json.email;
  if (typeof email === "string") {
    return {
      name: name,
      email: email,
    };
  }
}
```

</CodeTab>
